.. _Руководство по инсталляции сервиса конфигурации (бэкенда): ########################################################## Руководство по инсталляции сервиса конфигурации (бэкенда) ########################################################## ************************************************ Назначение и общий функционал работы с бэкендом ************************************************ *Бэкенд (англ. backend)* Представляет собой программно-аппаратную часть сервиса, набор средств, с помощью которых происходит реализация логики веб-сайта. Бэкенд для предоставления своих функций реализует API, которые использует фронтенд. *Фронтенд (англ. frontend)* Является клиентской стороной пользовательского интерфейса к программно-аппаратной части сервиса. Фронт- и бэкенд — это вариант архитектуры программного обеспечения. ****************** Установка бэкенда ****************** .. note:: Можно установить и настроить несколько экземпляров бэкенда. Все экземпляры бэкенда устанавливаются аналогично. О настройке см. `Настройка нескольких экземпляров бэкенда`_. Для установки бэкенда сначала необходимо установить Docker и Vault. Подробнее об установке и настройке Docker можно посмотреть здесь: https://docs.docker.com/get-started/. Подробнее об установке и настройке Vault см. :ref:`Руководство по инсталляции сервиса системных настроек Vault`. Если реестр Docker, содержащий образ бэкенда, недоступен или отсутствует, тогда необходимо скачать образ бэкенда из архивного файла, выполнив в командной строке команду: :: docker load -i /path/to/image.tar.gz Здесь: */path/to/image.tar.gz* Пример пути к архиву с образом бэкенда. Если реестр Docker, содержащий образ бэкенда, доступен, тогда для установки бэкенда нужно войти в реестр Docker, выполнив в командной строке команду: :: docker login registry.igtel.ru:6443 При входе необходимо ввести логин и пароль. После этого нужно скачать образ бэкенда из Docker, выполнив в командной строке команду: :: docker pull registry.igtel.ru:6443/sgate/backend После того как образ скачан (из архивного файла или из реестра Docker), необходимо запустить контейнер, выполнив в командной строке команду в многострочном формате (после символа :: \ должен быть перенос строки без пробелов и других символов): :: docker run -d \ --env SGATE_SERVER_HOST=0.0.0.0 \ --env SGATE_SERVER_PORT=8081 \ --env SGATE_VAULT_URL=http://devops.igtel.ru:8200 \ --env SGATE_VAULT_TOKEN=s.xRYEe6FCAHn1DAdOAqodkz4Z \ --env SGATE_VAULT_ENGINE=sgate \ --env SGATE_VAULT_VERSION=2 \ --env SGATE_VAULT_SOURCES="common backend" \ -p 8081:8081 --name sgate_backend \ registry.igtel.ru:6443/sgate/backend Здесь: *SGATE_SERVER_HOST* Хост сервиса в контейнере. *SGATE_SERVER_PORT* Порт сервиса в контейнере. Можно выбрать любой свободный порт в Системе. *SGATE_VAULT_URL* URL сервиса Vault с конфигурацией сервиса. *SGATE_VAULT_TOKEN* Токен для логина в Vault. *SGATE_VAULT_ENGINE* Название Vault engine, где хранятся настройки. *SGATE_VAULT_VERSION* Версия хранилища Vault. *SGATE_VAULT_SOURCES* Список секретов (secrets), которые будут использоваться сервисом. В примере это секреты "common" и "backend". Cекреты в списке разделяются пробелом. Секреты подгружаются в порядке, указанном в списке. Если секреты содержат одинаковые ключи, то значение для ключа берется из последнего секрета, в котором найден ключ. Таким образом, можно выделить общие настройки и переопределять их для нужных сервисов. *8081:8081* Указываются номер порта на сервере и номер порта в контейнере (порт на сервере маппится на порт в контейнере). *name* Указывается название контейнера для использования его при обращении (вместо идентификатора). В примере это "sgate_backend". *registry.igtel.ru:6443/sgate/backend* Образ бэкенда. .. _Общая настройка всех сервисов: ****************************** Общая настройка всех сервисов ****************************** Общая настройка всех сервисов заключается в добавлении общих для всех сервисов ключей и их значений в соответствующий секрет Vault. Ключи, общие для всех сервисов, удобно выделить в один секрет. Название секрета, содержащего ключи, общие для всех сервисов, может быть любым, например, "common". Для всех сервисов общими являются следующие ключи: ================================================ Параметры аутентификации ================================================ *basic.username* Логин к административной части сервиса (если она есть). *basic.password* Пароль к административной части сервиса (если она есть). *jwt.algorithm* Механизм проверки подлинности JWT (HS256, HS384 или HS512). *jwt.key* Ключ для подписи JWT в формате base64. Должен соответствовать механизму проверки. ================================================ Параметры SSL ================================================ *ssl.enabled* Включает/выключает поддержку SSL сервисом (true или false). *ssl.store-path* Путь к хранилищу ключей SSL в контейнере. *ssl.store-pass* Пароль к хранилищу ключей SSL. *ssl.key-pass* Пароль к ключу в хранилище. ================================================ Пример общих настроек ================================================ Пример заполнения общих для всех сервисов ключей в секрете: :: { "basic.password": "passwd", "basic.username": "login", "jwt.algorithm": "HS512", "jwt.key": "4bAKMH0ob8d2v4m0yOLuI/18psZgEo45AXnOQ9d9rd5Yzux4CnL5f1POQmrjJLCfg7Pn+8Ohqb8mGjlA/15Ciw==", "ssl.enabled": "true", "ssl.store-path": "keystore.jks", "ssl.store-pass": "storepasswd", "ssl.key-pass": "keypasswd" } ****************** Настройка бэкенда ****************** Настройка бэкенда заключается в добавлении ключей и их значений в соответствующих секретах Vault. Для бэкенда необходимо добавить следующие ключи в секрет/секреты Vault: ================================================ Параметры 2-х факторной авторизации ================================================ *2fa.secret.expire* Время жизни пароля двухфакторной аутентификации (2FA) в формате ISO 8601. PT5M означает 5 минут. Подробнее см. https://www.digi.com/resources/documentation/digidocs/90001437-13/reference/r_iso_8601_duration_format.htm. *2fa.secret.length* Длина пароля 2FA. ================================================ Параметры почтового сервера ================================================ *2fa.smtp.from* Email отправителя письма с паролем. *2fa.smtp.password* Пароль к SMTP-серверу. *2fa.smtp.url* URL SMTP-сервера. *2fa.smtp.username* Логин к SMTP-серверу. ================================================ Параметры подключения к адаптеру remedy ================================================ *adapter.username* Логин к адаптеру Remedy. Если не переопределено для адаптера, то совпадает с ключом basic.username (из ключей, общих для всех сервисов). *adapter.password* Пароль к адаптеру Remedy. Если не переопределено для адаптера, то совпадает с ключом basic.password (из ключей, общих для всех сервисов). ================================================ Параметры кеширования ================================================ *cache.concurrency-level* Настройка параллельного доступа к кэшу для операций обновления. Подробнее см. https://guava.dev/releases/18.0/api/docs/com/google/common/cache/CacheBuilder.html#concurrencyLevel(int). *cache.expire-after-write* Время жизни кэша в формате ISO 8601. *cache.initial-capacity* Начальный размер кэша. *cache.maximum-size* Максимальный размер кэша. ================================================ Параметры подключения к базе данных бекенда ================================================ *datasource.driver-class-name* JDBC драйвер для БД бэкенда. *datasource.jdbc-url* JDBC URL БД бэкенда. *datasource.username* Логин к БД бэкенда. *datasource.password* Пароль к БД бэкенда. ================================================ Параметры времени жизни JWT токена ================================================ *jwt.lifetime* Время жизни JWT в секундах. ================================================ Параметры подключения к LDAP ================================================ *ldap.user* Логин к LDAP. *ldap.password* Пароль к LDAP. *ldap.role_dn* Уникальное имя роли (LDAP role DN). *ldap.role_filter* Фильтр роли LDAP. *ldap.url* URL LDAP. *ldap.user_dn* Уникальное имя пользователя LDAP. *ldap.user_filter* Фильтр пользователя LDAP. ================================================ Параметры управления интеграционными маршрутами ================================================ *integration.enabled* Флаг (boolean) активации механизма интеграций (по умолчанию - true); *integration.sync.interval* Интервал синхронизации интеграций (маршрутов, эндпоинтов/ресурсов) в секундах (по умолчанию - 15 минут); *integration.sync.retry* | Параметр задержки в секундах перед повторной попыткой синхронизации. | Параметр требуется в случае возникновения ошибок, например, недоступности ресурса или в случае, когда уже выполняется ручная синхронизация. .. note:: Значение integration.sync.retry должно быть не больше значения integration.sync.interval. ================================================ Пример заполнения ключей для бэкенда ================================================ : :: { "2fa.secret.expire": "PT5M", "2fa.secret.length": "6", "2fa.smtp.from": "admin@example.ru", "2fa.smtp.password": "passwd", "2fa.smtp.url": "mail.example.ru:587", "2fa.smtp.username": "mail@example.ru", "adapter.username": "login", "adapter.password": "passwd", "cache.concurrency-level": "8", "cache.expire-after-write": "PT30S", "cache.initial-capacity": "32", "cache.maximum-size": "1024", "datasource.driver-class-name": "org.h2.Driver", "datasource.jdbc-url": "jdbc:h2:/var/db/sgate;SCHEMA=PUBLIC;DB_CLOSE_DELAY=-1;TRACE_LEVEL_FILE=1;DATABASE_TO_UPPER=false;MODE=Oracle;AUTO_SERVER=TRUE", "datasource.password": "123456", "datasource.username": "sa", "jwt.lifetime": "240", "ldap.password": "passwd", "ldap.role_dn": "ou=roles,dc=igtel,dc=ru", "ldap.role_filter": "(&(objectClass=groupofnames)(member={0}))", "ldap.url": "ldap://ci.igtel.ru:389", "ldap.user": "cn=admin,dc=igtel,dc=ru", "ldap.user_dn": "dc=igtel,dc=ru", "ldap.user_filter": "(&(objectClass=inetorgperson)(|(mail={0})(uid={0})))", "integration.enabled": "true", "integration.sync.interval": "900", "integration.sync.retry": "60" } .. ***************************************** Настройка лицензий ***************************************** Настройка лицензий приложения заключается в добавлении ключей и их значений в соответствующих секретах Vault: *license.key* для указания лицензии в текстовом виде *license.file* для указания лицензии в бинарном виде (указывается абсолютный путь к файлу на сервере или в контейнере/виртуалке) .. note:: Файл имеет больший приоритет, чем текстовый ключ. Если задан путь к файлу лицензии, для лицензирования используется он. .. note:: Лицензии необходимо разместить в секрете **common**, если лицензия не установлена подрядчиком. ***************************************** Настройка нескольких экземпляров бэкенда ***************************************** В некоторых случаях необходимо создать несколько экземпляров бэкенда. **Создание нескольких экземпляров бэкенда с одинаковым набором ключей в секретах Vault** требуется, например, для балансировки нагрузки на сервер и формирования отказоустойчивой Системы. **Создание нескольких экземпляров бэкенда с разным набором ключей в секретах Vault** позволяет, например, работать сразу с несколькими источниками данных (использовать несколько разных БД). Разные БД можно использовать для проведения A/B-тестирования. Все экземпляры бэкенда устанавливаются аналогично (см. `Установка бэкенда`_). Для каждого экземпляра бэкенда будет создан свой контейнер. Для каждого экземпляра бэкенда нужно выполнить настройку: в зависимости от целей создания дополнительного экземпляра бэкенда для него необходимо создать новые секреты в Vault или использовать уже существующие.